ProtectToolkit-J overview

ProtectToolkit-J is a Cryptographic Service Provider for the Java Cryptographic Architecture (JCA) / Java Cryptographic Extension (JCE) interface. ProtectToolkit-J implements a number of cryptographic algorithms that are supported by Thales's hardware encryption devices. These devices support encryption, signature generation and verification, message digests, key storage and message authentication. ProtectToolkit-J supports Java 7.x, 8.x, 9.x, 10.x, 11.x, 17.x, and 21.x.

This document assumes some knowledge of Java, the JCA/JCE application programming interfaces, and some understanding of the underlying adapter interface, which is based on PKCS#11 (Cryptoki). See ProtectToolkit-C administration for more information on Cryptoki. For general information on the JCA/JCE, refer to the following:

• JCA/JCE API overview

• JCA/JCE API tutorial

• JCA reference material found at http://docs.oracle.com/

This section does not discuss the security properties of the various algorithms in general; please refer to the standard cryptography texts for this information.

ProtectToolkit-J is known to the JCA/JCE by the provider name SAFENET. To request an algorithm implemented by this provider, the string "SAFENET" should be passed to the getInstance() method.

Prerequisites

ProtectToolkit-J requires the ProtectToolkit-C Runtime package and an Access Provider package that is relevant to your deployment. For more information about ProtectToolkit 7 packages and operating modes, refer to ProtectToolkit 7 software installation.

Available ProtectToolkit-J packages

The following ProtectToolkit-J packages can be found in the installation package:

• ProtectToolkit-J Runtime

  Includes the shared libraries required to interface to the ProtectToolkit-C Runtime, and the Java class libraries that implement the JCE specification and ProtectToolkit-J provider. Available as PTKjprt.msi on Windows and PTKjprov on Unix.

• ProtectToolkit-J SDK

  The software development platform. Available as PTKjpsdk.msi on Windows and PTKjpsdk on Unix.

Working with slots

ProtectToolkit-J is capable of interfacing to multiple adapters. This is achieved by using different "virtual providers" which map to each adapter. The virtual providers are named SAFENET.n, where n is the slot number as configured with the ProtectToolkit-C Runtime tools. The special provider SAFENET always maps to the first slot.

A provider class exists (SAFENETProvider) for each of the slots in the package au.com.safenet.crypto.provider.slot<n>. These providers can be statically installed or added dynamically by calling the SAFENETProvider.addProviders() method.

Resource management

Resource management is an important consideration when using the SafeNet provider. In general, creation of a provider instance (a Cipher object or Key object, for example) consumes resources within the adapter. This consumption is less than that of the main JVM and so the garbage collection is not tuned to its needs. The application programmer must therefore manage collection.

Two main techniques can be used:

• Explicitly track resource usage and invoke garbage collector on certain thresholds. For example, after the creation of 100 "session" Key objects, which are only required for a short transaction and then discarded, it may be necessary to run the garbage collector to clean up those unused instances.

• The second technique requires some tuning of the Cryptoki configuration on the adapter. If ProtectToolkit-J cannot create a new "session" with the adapter, it invokes the garbage collection (in the hope that there are some old unused sessions awaiting cleanup). By reducing the maximum number of sessions allowed by the adapter, the adapter can be tuned to the requirements of the application so that explicit resource management is not required.